Thank you for taking the trouble to try this program out. I hope you like it.
Note: this file is formatted and is best read with SimpleText and not TeachText.
Note: this file is not read-only so that you can easily copy the text if you want to. For example, you can copy the email addresses and URLs. Please don't modify this file or distribute modified versions.
Note: you should scroll up and down a pageful at a time so that the pictures will appear properly. If the pictures don't appear, you can make them appear by scrolling up a page and then back down a page.
This software is copyrighted material and therefore you are not allowed to modify this software or its documentation in any way, shape or form, nor can you sell it for your own profit. You may only charge a reasonable fee for the cost of distributing it. See the Distribution section below for information about how and on what IIe may be distributed.
Contents
The documentation for IIe comes in 2 files. Their contents are:
1. Read me first
What is it? - description, features, requirements and compatibilty notes
Description
Features
Hardware and software requirements
Compatibility
Installation and setup
Simple installation/setup
Tips
Instructions
A. Graphics modes
B. Disk inserting/removing instructions
C. Emulator instructions
2. Other stuff
Cost/fee and registration
Version history
Future version features
Distribution
Contacting the author
Other software by Vincent
Disclaimer
What is it? - description, features, requirements and compatibilty notes
Before getting started, some of the terms used below should be defined. "IIe" refers to this Mac program. "//e" refers to the actual Apple //e that you use in the "Apple //e" window, ie the virtual computer and not the Mac program and its menus, windows, dialogs, etc. Don't worry. It'll make more sense as you read along.
Description:
IIe is an Apple //e emulator for Macintoshes and PowerMacintoshes. It lets you run virtually any program for the Apple II, Apple II Plus, Apple //e, and Apple //c computers. It does not run Apple IIgs software.
It has been tested with a limited number of programs and works well with them. Most of the Apple II OSes boot up, including DOS 3.3, ProDOS 1.8 (not 2.0.3), and Apple Pascal. Most games will work without problems. See below for more details about this version's abilities and limitations.
How does it work? IIe takes machine instructions written originally for the 65c02 microprocessor and emulates them in software. In other words, it uses the CPU in your Mac to do the work that was originally intended for a 65c02 microprocessor. The emulator keeps track of the 65c02 instructions, registers and memory usage, as well as converting the memory used for graphics or text into Macintosh graphics. As well, Apple II peripherals such as the Disk II (5 1/4" disk drive), and the UniDisk are also emulated.
Note that the goal of this version is functionality, not a complete feature set nor great emulation speed - they are goals for version 2.0.
Features:
Ñ comes as a "fat binary" - that is, it contains both 680x0 and PowerPC code for optimal performance on any Mac
Ñ able to display an Apple //e computer in a Mac window. This version supports all the //e graphics modes: text, lores graphics, double lores graphics, hires graphics, and double hires graphics. It even flashes the text! The normal and alternate character sets are supported. The hires and double hires graphics can be displayed in monochrome or colour. Text and hires graphics displayed in monochrome mode can be displayed in a variety of monochrome colours such as white, green or amber (read that sentence twice if you didn't get it the first time)
Ñ able to take keystrokes on your Mac keyboard and pass them to the emulated //e. Supports the "open" (command) and "closed" (option) apple keys on the //e keyboard (as well as the third paddle button by the 'shift' key).
Ñ the //e can be reset from your Mac keyboard (by pressing control-delete)
Ñ able to read 5.25" disk and 3.5" disk images - this version supports 2 drives of each size
Ñ able to read directly from a 3.5" disk in the internal drive on your Mac and use it as a 3.5" disk in the emulator
Ñ able to switch any disk in any drive at any time
Ñ emulates a joystick by using the keypad on your Mac keyboard
Ñ this emulator cannot write to disks - this will be a feature of the next version (2.0)
Hardware and software requirements:
IIe requires:
Ñ a colour-capable Macintosh (ie, not the Mac Plus, SE, Portable, or PowerBook 100).
Ñ a 13" or 14" colour monitor (or larger) with support for 256 colours
Ñ System 7 or later.
Ñ the Thread Manager (which is a part of System 7.5 or later).
Recommended:
Ñ System 7.5.1 or later. This version was developed in 7.5.1 and has not been run in previous systems very much.
Ñ a fast 68040 Mac or a PowerMac, because this version isn't very fast - it's just usable on a low-end PowerMac. 68030 Macs won't enjoy this version at all. As stated above, the goal of this version is functionality, not a complete feature set nor great emulation speed - they are goals for version 2.0
Compatibility:
This software has been tested on systems 7.1 to 7.5.1.
This version does not allow background programs much background time to run so you may find print jobs tend to slow down and modem downloads don't work well. Similarly, programs that take up background time will tend to slow down the emulator (because your Mac's CPU spends less time running the emulator). Even having a lot of other programs open will slow down the emulator - merely closing those other 6 apps will bring a noticable speedup in the program. For best performance, close all unecessary programs and reduce the number of extensions you install at startup.
Currently there are no known software conflicts. If you should find a problem, let me know.
For Apple II programs, this version does not support writing to disks. Disk writing will be a supported feature in the next version (2.0).
Installation and setup
Simple installation/setup
To install and set up this program:
1) decompress the archive that this program comes in. You've probably already done this to be able to read this Read Me.
2) get a copy of the Apple //e ROMs*. If you're on the internet, you can get it from:
If you're on an online service, use its ftp ability to obtain the above file.
Use a utility such as "DropStuff with StuffIt Expander" or "ZipIt" to decompress it.
*For legal reasons, the ROMs cannot be distributed with this emulator because they are the copyright of Apple Computer, Inc. "So what?" you might ask. Well, I personally don't enjoy getting letters from lawyers, and since I still own an Apple //e (and it still works just fine thanks), I have all the ROMs I need (well, almost all: if only I'd bought that mouse card, memory card, serial card, etc. etc. when I could have...).
3) make sure the ROM file is called "APPLE2E.ROM" and that it is in the same folder as IIe. If you want to see the icon for ROMs, change the type/creator of the file to 'ROMs'/'AIIe'.
You are now set to use the Apple IIe emulator. Read the instructions below on how to use disks and disk images with IIe.
Tips
Ñ changing the creator of a disk image to 'AIIe' allows you to double click the file to have IIe use it
Ñ clicking the Mono/colour icon button changes the display from monochrome to colour and vice versa
Ñ control-clicking the Mono/colour icon button changes the colour of the monochrome text/graphics
Ñ option-clicking the Mono/colour icon button changes the screen's bit depth from 8 -> 1 -> 4 -> 8, etc.
Ñ control-esc or F15 will start/stop the emulator
Instructions
I will assume that you know how to use an Apple II computer, that is, you're aware of how to switch it on, insert a disk, boot a disk, remove a disk, use the keyboard and use the joystick. If you know these things then you'll find using IIe virtually the same as using an Apple //e except that the disk "insertion" and "removal" activities are virtual instead of real (unless you insert a real floppy disk into your Mac in which case it's real - hmmm, are you confused yet?).
If you don't know how to use an Apple II, just try using IIe anyway. Please don't send me e-mail asking for this kind of help - as it is, I don't have enough time to write more code so I won't spend time unproductively answering your questions. Instead, trying posting a message to an Apple II message board. Be polite and explain your ignorance of the Apple II. There should be some kind soul to help you out. If you're on the internet, try the USENET newsgroups such as 'comp.sys.apple2.<something>' or 'comp.emulators.apple2'.
Special note: as with a real Apple //e, if you don't insert any disks into any drive and you then run the emulator, it will appear to not do anything. This is because, as on a real //e, it is trying to "boot" a non-existant disk. To get out of this, you should insert a disk and press command-control-delete to boot it.
The following instructions pertain only to features specific to this emulator.
A. Graphics modes
Ñ IIe shows you the //e's screen in a Mac window. This window should always be located on the same screen as your menu bar. If you have more than one monitor connected, please do not drag the window to a different monitor because IIe currently does not support multiple monitors.
Ñ normal 40 column text, 40 column lores and "normal" hires graphics can be displayed in either a small 280 * 192 area or in a larger 560 * 384 area. You can alternate between the two sizes by clicking the window's zoom box.
Ñ 80 column text, 80 column lores and double hires graphics must be displayed in the large 560 * 384 window. You cannot switch to a smaller display whilst any of these modes are active, and activating any of these modes (such as "PR#3 [return]" from BASIC) will make the emulator switch to the larger size.
Ñ clicking the mono/colour icon button changes the display of hires graphics and double hires graphics from monochrome to colour and vice versa. It does not affect text or lores graphics. Naturally, this button does nothing if your Mac's monitor is set to display black-and-white (1 bit depth).
Ñ clicking the mono/colour icon button whilst holding down the option key changes the depth of the Mac monitor. The depth is rotated from 256 colours (8-bit) to black-and-white (1-bit) to 16 colours (4-bit) and then back to 256 colours (8-bit).
Ñ clicking the mono/colour icon button whilst holding down the control key changes the colour of the monochrome colour. Text is displayed in this colour and so will be affected, as will hires graphics and double hires graphics if the display is set to monochrome (by clicking the mono/colour icon button by itself). Note: control-clicking the icon does nothing if your Mac's monitor is set to display black-and-white (1 bit depth).
B. Disk inserting/removing instructions
You can insert either a real 3.5" disk into the disk drive and use it with IIe, or you can use a disk image - a (Mac) file that "contains" an Apple II "disk".
To use a real disk, run IIe and then insert your disk. You will be asked which IIe "drive" you want to "insert" it into. Select your drive and you're set to use that disk. Note that although you can insert a Mac formatted disk into the IIe's drive, it won't be very useful. For all practical purposes, you should insert a ProDOS formatted disk into IIe's drive (see below for info about ProDOS).
However, to use a disk image, you need to prepare the file properly before you can "insert" it into a IIe "drive". A short description of why this is necessary and how to do this follows.
On the Apple II, there are 2 main file systems: DOS 3.3, an older format (and probably the more commoner of the two) which usually supports only 5.25" disks; and ProDOS, the newer system which supports different sized disks. The order and format of data on these two systems are completely different from each other, and therefore disk images of disks in these systems are completely different in order and format from each other. As well, there is another file system called Apple Pascal, but isn't used much (Wizardry is probably the most famous program that used it).
Most of the disk images of 5.25" disks that are available on the internet are in "DOS 3.3" order and are stored as plain compressed (usually gzipped) binary files. They usually have a ".dsk" suffix. So a typical file is stored as 'coolgame.dsk.gz'. This is for the benefit of PC users. When you download such a file to your Mac and decompress it, the file is usually of the wrong Macintosh file type and creator (for example, StuffIt Expander decompresses such files to SimpleText text files: type 'TEXT', creator 'ttxt'). To use the disk image file with IIe, you need to change the type to one that IIe can use. The file's type should be changed to 'DSK5' and its creator to 'AIIe'. When you do this, the file can be double clicked and then opened by IIe.
Most of the 3.5" disk images are similar to the 5.25" disk images except that they are usually in "ProDOS" order. Aside from that, they are usually stored as plain compressed (usually gzipped) binary files. Again, they usually have a ".dsk" suffix. Again, they'll have the wrong Macintosh file type and creator. To use the disk image file with IIe, you need to change the type to 'DSK3' and its creator to 'AIIe'. When you do this, the file can be double clicked and then opened by IIe.
For Mac users, a convenient format for 3.5" disks is the Apple Disk Copy format. This is the format that is created by disk imaging software such as Apple's Disk Copy 4.2 or Chad Magendanz's ShrinkWrap. Such disk images have "ProDOS" ordering. This format is different to the 'plain' 3.5" disk image that is usually found on the internet. Disk Copy images have extra data at the beginning of the image to identify the image's format. Disk images in this format have the file type 'dImg'. This does not need to be changed for IIe to use them: you can drag and drop those files onto IIe's icon. However, if you want to be able to double click the disk image and have IIe open it, you'll need to change it's creator to 'AIIe'. The nice thing about this format is that you can mount these files on your Mac desktop with ShrinkWrap and ProDOS File System installed. You can then modify them.
Finally, there are disks stored in hard disk volume format. They usually have a ".hdv" suffix. They are ProDOS ordered files and are usually images of Apple II hard disks. They aren't common but are supported nonetheless. They have a file type 'HDV ' (note the space at the end). Change the file's creator to 'AIIe' so you can double click them into IIe.
To change a file's type or creator, use a file type editor such as ResEdit (Apple), BunchTyper, FileTyper, or Aladdin's Desktop Tools.
After the disk image file is set up for use, you can drag it to IIe or just double click if it's creator is set to 'AIIe'. You can also select "Insert Disk Image╔" from the File menu or click the "Insert╔" icon button. IIe will then ask you which //e slot and drive to insert the disk into. IIe supports 2 5.25" drives and 2 3.5" drives.
You can remove disks by selecting "Remove Disk Image╔" from the File menu or click the "Remove╔" icon button. In the dialog that appears, select which disks you want to remove and click Remove. Note that you do not need to remove a disk before inserting a new one; newly inserted disks displace disks that are already in that drive (that is, the old one is automatically removed for you).
C. Emulator instructions
Starting up the emulator:
If you start IIe with a disk (by double clicking the disk image's icon or by dragging it to IIe's program icon), the emulator will start running as soon as it is ready and the disk "inserted".
However, when you start IIe without any disks in any drive, the emulator won't run until you tell it to. You can start it up by clicking the "Run/Stop" icon button. Pressing it again will stop it. Alternatively, you can press F15. The icon will change to show you the state of the emulator. Of course, it isn't very useful without a disk╔
Bonus: if you start IIe up with the command key held down, then IIe will use the title of the //e window to show you how many 65c02 clock cycles it has emulated in each of its emulation cycles (which are about half a second long).
The Reset key:
To "reset" the //e, that is, simulate a pressing of a real //e's reset key, press control-delete (the delete key here acting like the reset key) or the "Reset" icon button. Tip: to force a "cold" reboot, press command-control-delete or command-click the "Reset" icon button. If you want to see the //e diagnostic test, press option-control-delete (or option-click the "Reset" icon button), but the test is kind of boring in my opinion╔
Keyboard:
When the emulator is running, all keystrokes are directed to the //e window. When the emulator is not running, all keystrokes are directed to the IIe program, that is, the menu bar. So if you press command-I to insert a new disk and nothing happens, be sure that the emulator is not running. If it is running, press control-esc or F15 or the "Run/Stop" icon button, to first halt it and then press command-I (or just click the "Insert╔" icon button).
Note: the <delete> key on the Mac keyboard is mapped to the <backspace> key on the //e. You cannot send a <delete> key to the //e in this version (sorry AppleWorks users). This will be fixed with an option in the next version.
Paddles and buttons:
The "open" and "closed" apple keys on the //e keyboard (paddle 0's button and paddle 1's button respectively), as well as the third paddle button are supported. The Mac keys to use are command, option and shift respectively.
The paddles/joystick is currently emulated by the Mac keypad. Keypad 7 is the same as pushing the joystick to the top-left. Keypad 3 is the same as pushing it to the bottom-right. Keypad 1 pushes it to the bottom-left. Keypad 9 pushes it to the top-right. The other keypad keys push it in between the corners. I've found that this arrangements works quite well - most programs I've tried it with have no problems with it.
Because this emulator uses a "smart" paddle emalation routine (technical weenies: it counts clock cycles), you should find that all paddle applications work well - even those programs that read both paddles at the same time! If you find a program that doesn't work well with the paddles, let me know and I'll investigate it.
Misc:
The Prefs and Setup commands are non-functional, as are the Load/Save IIe Image, and New Disk Image commands. They will work in the next version.
